home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / gemfut15.lzh / GEMUTIL.DOC < prev    next >
Text File  |  1990-06-29  |  28KB  |  558 lines
  1.  
  2. **************************************************************************
  3. *
  4. * GEMUTIL.DOC - Descriptions of the utility functions in GEMFAST.
  5. *
  6. *  05/26/90 - v1.4
  7. *             The rsc_gstrings()/rsc_sstrings() routines now support ICONs.
  8. *             The following functions are new with this release:
  9. *               frm_dsdial()
  10. *               obj_rbselect()
  11. *               obj_xtfind()
  12. *
  13. *  08/28/89 - v1.3
  14. *             Massive changes have been made to the utilty routines, and
  15. *             to this document.  Your best bet is to read the entire doc
  16. *             over again.
  17. *
  18. *             Most of the changes involve renaming routines to move toward
  19. *             a consistant naming standard (which is to pave the way for
  20. *             things planned for v2.0).  I've done my best to cover the
  21. *             name changes with #define statements in GEMFAST.H, so your
  22. *             existing code should work, but you should make every effort
  23. *             to convert existing and new code to the new names.  Sorry,
  24. *             I guess I wasn't thinking far enough ahead when I did the
  25. *             first release.
  26. *             
  27. *             For all the renamed routines, I've put the old name in
  28. *             the title bar of the new function's name.
  29. **************************************************************************
  30.  
  31. This document describes the functions in the AESUTxxx modules of the
  32. GEMFAST bindings.  These are not GEM function calls, and thus are not
  33. documented in standard GEM programming guides.
  34.  
  35. Within this document, the most changes will be indicated by a vertical bar 
  36. and the change level (|vX.X).
  37.  
  38. Definitions:
  39.  
  40. NO_OBJECT - A constant defined in GEMFAST.H; it has a value of -1.  This
  41.             value is used by most object-related utilties to indicate that
  42.             no object was found with the criteria specified in the search
  43.             (eg, for objc_find(), obj_rbfind(), etc).
  44.  
  45. GRECT     - A graphics-type rectangle of the form x,y,w,h.  A GRECT
  46.             describes a screen area by defining the x/y of the upper left
  47.             corner, and the width and height of the area.
  48.  
  49. VRECT     - A vdi-type rectangle of the form x1,y1,x2,y2.  A VRECT
  50.             describes a screen area by defining the upper left and lower
  51.             right corners of the area in x/y coordinates.
  52.  
  53. xRECT     - Used to indicate that either of the above types is accepted.
  54.  
  55. ;*************************************************************************
  56. ; Rectangle utilties.
  57. ;*************************************************************************
  58.  
  59. ;-------------------------------------------------------------------------
  60. ; rc_copy
  61. ;-------------------------------------------------------------------------
  62.  
  63. void rc_copy (xRECT *source, xRECT *dest)
  64.  
  65.         This function copies a rectangle.  It will copy either a GRECT or
  66.         VRECT type rectangle.  More generally, it will copy 2 longwords
  67.         from source to dest, they don't have to be rectangles at all.
  68.          >> NOTE BACKWARDS ORDER OF SOURCE & DEST.  Sorry, not my decision.
  69.  
  70. ;-------------------------------------------------------------------------
  71. ; rc_equal
  72. ;-------------------------------------------------------------------------
  73.  
  74. bool rc_equal(xRECT *rect1, xRECT *rect2)
  75.         
  76.         This function tests 2 rectangles for equality and returns TRUE/FALSE
  77.         (1/0) accordingly.  Works on GRECT or VRECT type rectangles, but
  78.         both rectangles must be of the same type.  More generally, this
  79.         function compare 2 sets of 2 contiguous longwords.
  80.  
  81. ;-------------------------------------------------------------------------
  82. ; rc_intersect
  83. ;-------------------------------------------------------------------------
  84.      
  85. bool rc_intersect(GRECT *rect1, GRECT *rect2)
  86.  
  87.         This function computes the intersection of 2 rectangles.  It works
  88.         only for GRECT type rectangles.  The intersection is the parts of 
  89.         two rectangles which overlap each other; this function is typically
  90.         used in processing the AES window-update rectangle list.  The result
  91.         is placed into 'rect2', overlaying the original data (again, not my
  92.         decision).  TRUE/FALSE is returned, depending on whether the 
  93.         rectangles had a common intersected area or not; the values in 
  94.         'rect2' are modified regardless of whether there was an intersection or not.
  95.         If the rectangle representing the intersecting area has a width or
  96.         height of zero, this routine will return TRUE.
  97.  
  98. ;-------------------------------------------------------------------------
  99. ; rc_union
  100. ;-------------------------------------------------------------------------
  101.  
  102. void rc_union(GRECT *rect1, GRECT *rect2)
  103.  
  104.         This function computes the union of two rectangles.  The union is 
  105.         the single rectangle that encompases all the area defined by the 
  106.         individual rectangles.  It works only for GRECT type rectangles.  
  107.         The result is placed into 'rect2'.
  108.  
  109. ;-------------------------------------------------------------------------
  110. ; rc_vtog
  111. ;-------------------------------------------------------------------------
  112.      
  113. void rc_vtog(VRECT *rect1, GRECT *rect2)
  114.  
  115.         This function converts a VRECT rectangle to a GRECT rectangle.
  116.         Do not specify the same rectangle for input and output.
  117.  
  118. ;-------------------------------------------------------------------------
  119. ; rc_gtov
  120. ;-------------------------------------------------------------------------
  121.         
  122. void rc_gtov(GRECT *rect1, VRECT *rect2)
  123.  
  124.         This function converts a GRECT rectangle to a VRECT rectangle.
  125.         Do not specify the same rectangle for input and output.
  126.  
  127. ;-------------------------------------------------------------------------
  128. ; rc_vadjust            (formerly objclv_adjust)
  129. ; rc_gadjust            (formerly objclg_adjust)
  130. ;-------------------------------------------------------------------------
  131.         
  132. void rc_vadjust(VRECT *rect, int h_adjust, int v_adjust);
  133. void rc_gadjust(GRECT *rect, int h_adjust, int v_adjust);
  134.  
  135.         These functions expand or contract a rectangle by a given amount
  136.         in each axis. A positive value exands the area, a negative
  137.         value contracts it.  You must use rc_gadjust for GRECTs and
  138.         rc_vadjust for VRECTs.  
  139.         
  140. |v1.3   Negative results are prevented by the adjust routines; zero will be 
  141. |       placed into any rectangle structure element which would have been 
  142. |       negative after the adjustment.
  143.         
  144. ;*************************************************************************
  145. ; Object utilities.
  146. ;*************************************************************************
  147.  
  148. ;-------------------------------------------------------------------------
  149. ; obj_flchange          (formerly objfl_change)
  150. ;-------------------------------------------------------------------------
  151.  
  152. void obj_flchange(OBJECT *tree, int object, int flagsmask, int updateflag);
  153.  
  154.         This function sets or resets bits in an object's ob_flags field.
  155.         Depending on the setting of 'updateflag' the object is updated 
  156.         on the screen or not. (Update is done via objc_draw internally).
  157.         If the high bit of 'flagsmask' is set, the flags bits are reset,
  158.         otherwise they are set.  This allows the following syntax:
  159.            objfl_change(mytree, myobj,  HIDETREE, TRUE);
  160.            objfl_change(mytree, myobj, ~HIDETREE, FALSE);
  161.         The first case will set 'myobj' to hidden and will erase it from
  162.         the screen.  The second case will set 'myobj' to visible, but does
  163.         not update the screen.
  164.         
  165.         Note that you CAN use this function to hide and unhide trees
  166.         visibly on the screen.  When the objc_draw is called internally
  167.         by this function, the draw starts at the root of the tree, but is
  168.         clipped by the x/y/w/h of the object who's state is being changed.
  169.         This means that a flag change to HIDETREE with update will draw
  170.         the parents of the hidden objec